BBS Toolkit/BBS Toolkit.iso/doors_2/sdoor102.zip/SDOOR.DOC

Text File | 1992-04-02 | 19KB | 551 lines

                             Simple Door v1.02b

                            by SumWare Software
                           Programmer: Roy Hooper
                        Beta Basher: Rick Chartrand
                     Documentation : Michelle Chartrand

                 Simple Door can be registered for $35 Cdn.


        Simple Door was written for the use of anyone wishing to make a
        door in QuickBasic 4.5.  Simple Door's main purpose was to create a
        good, easy way to make good doors.

        Simple Door is a collection of routines that handle communications
        through a FOSSIL driver and manage the user's time limit, and
        carrier.  There are routines ranging from sending a string to
        sending a file, getting a character and getting a string.

        Simple Door has many things to make your door look nice, including
        only using ANSI routines if the user supports ANSI, and a status bar
        with plenty of bits of information on it.  The status bar also has a
        few controls on it which allow you to chat with the user, and
        increase or decrease the user's time.  You can shell to DOS, boot
        the user out of the door, or even turn off snoop.

        Simple Door is multi-node compatible, as it does no disk I/O and
        relies on the door file for information on where to do its
        communications I/O.  If you wish to support multi node, then your
        door must support multinode internally.

        Simple Door does error handling for any error that might occur
        internally.  If an error that it cannot handle occurs, then it will
        just state it and exit.  Simple Door does not do error handling for
        your program, only errors internal to Simple Door.  If you wish to
        learn more about error handling for your program, take a look at ON
        ERROR in your QuickBasic 4.5 manual.

- Using Simple Door -

        To use Simple Door inside one of your program, you need to include
        the SDOOR.BI file.  SDOOR.BI can be located in your INCLUDE
        directory, or in your QuickBasic program directory, or the current
        directory.  SDOOR.QLB and SDOOR.LIB has to be located in a place
        that QuickBasic can find then when it loads  up (usually your
        LIBRARY directory or the QuickBasic program directory, or the
        current directory).

        When loading QuickBasic, you need to tell QuickBasic about the
        library.  To do this, you need to specify the library on the command
        line.  Example:

        QB /LSDoor

        Inside your program, after your DECLARE SUB/FUNCTION lines, if any,
        you need to place the following line:

        '$INCLUDE: 'SDOOR.BI'

        And then you are ready to program with Simple Door. (Don't forget to
        initialize Simple Door).  One thing to keep in mind is Simple Door
        has a 4 minute timeout limit.  After 3 minutes 30 seconds of no
        keypresses, SDoor warns you with a beep that you have 30 seconds to
        do something.


- What Simple Door Can Do -


                                 FUNCTIONS

   AColor$ (Fore%, Back%)
        Makes an optimized ANSI color string
        Fore% = Foreground color to use
        Back% = Background color to use

        EXAMPLE:
                Send AColor$(7,1)+"White on blue"

       (q.v. SetColor for a complete list of colors)

   CtrlCK% ()
        Checks if Control C/K have been checked.  Also enables Control C/K
        checking.  Returns -1 if true, 0 if not true.

        EXAMPLE:
                IF CtrlCK% THEN
                        FlushOut
                        SendCr "Aborted."
                END IF

   Exist% (FileName$)
        Returns a non-zero value if the file exists.

        EXAMPLE:
                IF Exist%("TEST.TTT") THEN Send "File FOUND"

   GetAnsi% ()
        Gets the current ANSI setting.  Returns -1 if true, 0 if not true.

        EXAMPLE:
                AnsiMode%=GetAnsi%
                IF AnsiMode% THEN
                        SendCr "Ansi is active"
                ELSE
                        SendCr "Ansi is not active"
                END IF

   GetBBSName$ ()
        Gets the bbs's name,  in all uppercase.

        EXAMPLE:
                Send "This program is registered to : " + GetBbsname$

   GetBaudRate& ()
        Gets the current baud rate of the user (Door Info).  0 if local.

        EXAMPLE:
                Send "You are running at" + STR$(GetBaudRate&)

   GetCarrier% ()
        Gets the current carrier state.  Non-zero if there is a carrier.
        The user's carrier is automatically managed.  This is not really
        needed.

        EXAMPLE:
                IF GetCarrier% THEN Send "YOU ARE STILL CONNECTED"

   GetPort% ()
        Gets the current serial port setting.  -1 if local

        EXAMPLE:
                Send "You are on com port" + STR$(GetPort%)

   GetSecLevel& ()
        Gets the user's security level.

        EXAMPLE:
                Send "Your security Level is" + STR$(GetSecLevel&)

   GetSnoopState% ()
        Gets the status of the snoop setting on the SysOp's side.
        Returns -1 if true, 0 if not.

        EXAMPLE:
                IF GetSnoopState% THEN
                        Send "Snoop is ON"
                ELSE
                        Send "Snoop is OFF"
                ENDIF

   GetSysopName$ ()
        Gets the sysop's name,  in all uppercase.

        EXAMPLE:
                Send "Your sysop is: " + GetSysopname$

   GetTimeLeft% ()
        Gets the amount of time the user has left in minutes.

        EXAMPLE:
                Send "You have" + STR$(GetTimeLeft%)+" minutes left."

   GetUserLocation$ ()
        Gets the user's location (DOOR INFO) in all uppercase.

        EXAMPLE:
                Send "Your location is: " + GetUserLocation$

   GetUserName$ ()
        Gets the user's name (DOOR INFO) in all uppercase.

        EXAMPLE:
                Send "Your name is: " + GetUserName$



                                SUBROUTINES

   Center (St$)
        Centers the specified text and stays on the same line.

        EXAMPLE:
                Center "Testing the centering routine"

   CenterCr (St$)
        Centers the specified text and creates a new line.

        EXAMPLE:
                CenterCr "Testing the centering routine"

   Chat ()
        Starts a chat mode with the user.  Restores the colors to normal
        afterwards.

        EXAMPLE:
                SendCr "Forced CHAT:"
                Chat


   ClearScreen ()
        Clears the screen

        EXAMPLE:
                ClearScreen

  ComParms (BaudRate&, Flag$)
        Sets the communications parameters.  These are already set upon
        initialization.  There should be no need to play with them.

        BaudRate& can be:  300, 600, 1200, 2400, 4800, 9600, 19200, 38400
        Flag$ takes the form of: "8N1" where the 8 can be replaced by:
                                        5, 6, 7, 8   (Data bits)
                                 and the N can be replaced by:
                                        N, O, E      (Parity)
                                 and the 1 can be replaced by:
                                        1, 2         (Stop bits)

        EXAMPLE:
                ComParms 2400, "8N1"

   CtrlCKOn ()
        Turns on Control-C/K checking.

        EXAMPLE:
                CtrlCKOn

   CtrlCKOff ()
        Turns off Control-C/K checking.

        EXAMPLE:
                CtrlCKOff

   DeInitialize ()
        Turns off the status bar and removes it from the screen.  Disables
        the door driver and turns off the door driver's internal error
        checking.  Also causes Send, SendCr, and all other routines to
        malfunction.  DO NOT DO ANY OTHER DOOR DRIVER CALLS AFTER
        DE INITIALIZING!  DOES NOT TERMINATE THE PROGRAM.

        EXAMPLE:
                DeInitialize
                Print "Cleaning up after door"
                END

   DetectAnsi (Ansi%)
        Detects Ansi (Remote user)
        Returns -1 or 0 into Ansi% (or any other variable of your choice)

        EXAMPLE:
                DetectAnsi Ansi%
                SetAnsi Ansi%

   FlushIn ()
        Flushes the inbound modem buffer.  Wipes all user keystrokes.

        EXAMPLE:
                FlushIn
                Send "What now sire? "
                GetChar ToDoThis$
                SendCr ToDoThis$

   FlushOut ()
        Flushes the outbound modem buffer.  Usefull for stopping screens
        when Control-C/K have been pressed.

        EXAMPLE:
                SendCr "Press Control-C/K to stop this mess"
                CtrlCKOn
                DO
                        SendCr "Testing 1234567890..."
                       I$ = Inkey$
               LOOP UNTIL I$ = CHR$(3) OR I$ = CHR$(11) OR CtrlCK%
               SendCr "Aborted."

   GetChar (Ch$)
       Gets a character from the modem into Ch$.  (Ch$ can be any
       variable)

       EXAMPLE:
               SendCr "Yo there dude!  Press any key please!"
               GetChar Test$
               SendCr "Thanks!"

   GetColor (Fore%, Back%)
       Gets the current foreground and background colors.

       EXAMPLE:
               GetColor ForeGround%, BackGround%
               SendCr "The foreground color is: " + STR$(ForeGround%)
               SendCr "The background color is: " + STR$(BackGround%)

   GetCurPos (X%, Y%)
       Gets the cursor position.
       X% = The Current Row
       Y% = The Current Column

       EXAMPLE:
               GetCurPos X%, Y%
               SendCr "The row is: " + STR$(X%)
               SendCr "The column is: " + STR$(Y%)

   GetString (St$, Max%, Mode%)
       Gets a string from the modem/console.
       St$ = The returned string.
       Max% = The max width/value.
       Mode% = Input mode:
               0  :-   Normal Input, exactly as entered.
                       Max% = Maximum length in characters.
               1  :-   UserName Input, Every first character of a word is
                       converted to uppercase.  Uppercase characters after
                       the first letter of each word are accepted.
                       Max% = Maximum length in characters.
               2  :-   Numeric input.  Allows from 0 to the number specified.
                       Allows blank strings for 0.  Returned value is a
                       string.
                       Max% = Maximum value (Integer value; 0 - 32767)
               3  :-   Password input.  Outputs dots (.) instead of entered
                       characters.  Case insensitive.
               4  :-   Telephone number.  Allows all numbers, brackets ()
                       and the dash.

       EXAMPLES:
               GetString Test$, 20, 0  'Gets a string of 20 characters long
                                       'into Test$ with no restrictions.
               GetString Test$, 20, 1  'Gets a string of 20 characters long
                                       'into Test$, with username style
                                       'input.
               GetString Test$, 128, 2 'Gets a number into Test$.  Max 128
               GetString Test$, 20, 3  'Gets a password of 20 chars max.
               GetString Test$, 14, 4  'Gets a telephone number of 14 chars
                                       'maximum.

   Hangup ()
       Hangs up the user.

       EXAMPLE:
               Hangup

   Initialize (DOORFile$, ProgName$)
       Initializes the door driver routines.
       DOORFile$ = The path and filename of the DORINFOx.DEF file
       ProgName$ = The name of the door.  Only for registered versions.

       EXAMPLES:
               DoorFile$ = "\BBS\DORINFO1.DEF"
               Initialize DoorFile$,"Test Door"


   LineFeed (Lines%)
       Sends (Lines%) CR/LF pairs.

       EXAMPLE:
               LineFeed 20

   OfficePhone (Duration!)
       Makes a sound similar to an office phone until any key is pressed
       or the number of seconds specified in Duration! has elapsed!

       EXAMPLE:
               OfficePhone 30

   ReInitPort ()
       ReInitializes the com port.  Not needed, but here anyways.

       EXAMPLE:
               ReInitPort

   ResetIdle ()
       Resets the idle time counter to zero.
       Is called upon every Send, SendCr, GetChar (after key press),
       GetString, SendFile, SetColor, Center, CenterCr.

       EXAMPLE:
               ResetIdle

   Send (St$)
       Sends the specified string to the modem/screen if snoop is on.
       St$ = The string to send.

       EXAMPLE:
               Send "Testing 123"

   SendCr (St$)
       Sends the specified string to the modem/screen and appends a CR/LF
       pair at the end of it.
       St$ = The string to send.

       EXAMPLE:
               SendCr "This is on the line above the line below."
               SendCr "This is on the line below the line above."

   SendFile (FileName$, More%, Ck%, Er%)
       Sends a file to the modem/screen.
       FileName$ is the full path/filename of a file to display.  Defaults
        to the current directory.
        If the extension is supplied, your program must determine itself if
        the user supports ANSI or not.  If you do not supply an extension,
        the door driver will attempt to locate a .ANS file if the user has
        ANSI active, if not, it will resort to ASCII (.ASC) and if that
        fails, it will then assume "File not found".
       More% is the toggle for the More prompt.  A non-zero value will
        activate it.  A user can use Ctrl-C/K as a "NO" at the More prompt.
       Ck% is the toggle for Control-C/K aborting.  If this value is
        non-zero, then Ctrl-K/C from either side will stop the file from
        being displayed.  If you want the user to be forced to see the
        whole file, then I recommend making your own sendfile routine and
        making it ask for any key to continue once per x lines.
       Er% is set to a non-zero value if the file isn't found.
       This routine cannot handle disk IO errors, so the Simple Door error
       handler is called upon to do the dirty work.  This means the game
       will terminate.

       EXAMPLE:
               SendFile "TEST",0,1,Er%
               IF Er% THEN SendCr "Hey, where'd my file go?"

   SetAnsi (AnsiState%)
       Sets the user's ANSI state.  Not recommended unless the user changes
       it himself.

       EXAMPLE:
               Send "You have ANSI "
               AnsiMode%=GetAnsi%
               IF AnsiMode% THEN
                       SendCr "enabled"
               ELSE
                       SendCr "disabled"
               ENDIF

   SetColor (Fore%, Back%)
       Sets the color.
       Fore% = Foreground color

        Color systems------------------------- Monochrome systems-------

        0  - Black        1  - Blue            0 -  Black
        2  - Green        3  - Cyan            1 -  Underline
        4  - Red          5  - Magenta         2 to 7 -  Normal
        6  - Brown        7  - White           8 -  Black
        8  - Gray         9  - Light Blue      9 -  Intense Underline
        10 - Light Green  11 - Light Cyan      10 to 15 -  Intense
        12 - Light Red    13 - Light Magenta
        14 - Yellow       15 - Light White

       Back% = Background color

       Color systems-------------------------- Monochrome systems-------

        0  - Black        1  - Blue            0 to 6 -  Black
        2  - Green        3  - Cyan            7 -  White (Only with 0 as
        4  - Red          5  - Magenta              foreground)
        6  - Brown        7  - White

       EXAMPLE:
               SetColor 7,1            'White on blue

   SetCurPos (X%, Y%)
       Sets the cursor position (ONLY WHEN ANSI IS ACTIVE)
       X% = Row%
       Y% = Col%
       WARNING: No internal checking for the Row% is done.  It must not
       exceed 24 if you want to maintain compatibility with old ANSI
       terminals.

       EXAMPLE:
               SetCurPos 9, 1

   SetIdle (IdleTim%)
       Sets the idle timeout value (defaults to 240 seconds on startup)
       IdleTim% = number of seconds before idle timeout.  Gives idle
        warning at 30 seconds left.

       EXAMPLE:
               SetIdle 250

   SetSnoopState (SnSt%)
       Sets the Snoop state.
       SnSt% - The snoop state flag.  Any non-zero value turns on snoop.
       Zero turns it off.

       EXAMPLE:
               SetSnoopState -1

   StatBarOff ()
       Turns off status bar updates (and disables carrier/time limit
       checking)
       GOOD FOR DISK I/O WHEN REWRITING DATA FILES!

       EXAMPLE:
               SendCr "Updating Data file"
               StatBarOff
               .
               .
               .
               StatBarOn

   StatBarOn ()
       Turns on the status bar.  (and enables carrier/TIME LIMIT checking)

       EXAMPLE:
               [See Previous Command]

   StatusBar ()
       Forces an update of the status bar.

       EXAMPLE:
               StatusBar

   ToggleSnoop ()
       Toggles the snoop setting.

       EXAMPLE:
               ToggleSnoop


                           - License Agreement -

        Roy Hooper and the SumWare group do not make any warranties on this
product.  We are not responsible for damage caused by the use or inability
to use this software.  Use of this software constitutes agreements to these
terms. In order for you to release your own programs using Simple Door, you
must register it at $35 Cdn.  Registering this software will provide you
with a registered version 1.00 on a diskette.  Future versions will be
available at a cost of $10 Cdn upgrade fee (mailed on a disk) to registered
users . Updates will be posted in the QUIK_BAS echo and a few others that
are appropriate. Or if you run a bulletin board we will send netmail to
notify you of impending releases. You can contact either Roy Hooper or Rick
Chartrand in the QUIK_BAS echo or by netmail to their node numbers for any
questions relating to Simple Door.

Please see the registration form for complete details.

Our Netmail Addresses are the following.

               Roy Hooper                      Rick Chartrand
               1:243/[e-mail]            1:243/[e-mail]
               50:5613/[e-mail]         50:5613/[e-mail]
               100:649/[e-mail]              Echo Valley
               18:613/[e-mail]            Phone # [phone]
               Parity Error BBS                2400 bps
               Phone # [phone]
               2400Bps

Other SumWare Software products are available at at the following BBS'es

Echo Valley              613-749-1016 1:243/26 2400bps
Parity Error             613-737-0966 1:243/30 2400bps
The Land Of The Cult BBS 613-830-0706 1:243/31 14.4 DS HST